home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1999 #2 / Amiga Plus CD - 1999 - No. 2.iso / System / mui / developer / autodocs / muimaster.doc < prev   
Text File  |  1977-12-31  |  20KB  |  690 lines
  1. TABLE OF CONTENTS
  2.  
  3. muimaster.library/--background--
  4. muimaster.library/MUI_AllocAslRequest
  5. muimaster.library/MUI_AslRequest
  6. muimaster.library/MUI_CreateCustomClass
  7. muimaster.library/MUI_DeleteCustomClass
  8. muimaster.library/MUI_DisposeObject
  9. muimaster.library/MUI_Error
  10. muimaster.library/MUI_FreeAslRequest
  11. muimaster.library/MUI_FreeClass
  12. muimaster.library/MUI_GetClass
  13. muimaster.library/MUI_MakeObjectA
  14. muimaster.library/MUI_NewObjectA
  15. muimaster.library/MUI_ObtainPen
  16. muimaster.library/MUI_Redraw
  17. muimaster.library/MUI_ReleasePen
  18. muimaster.library/MUI_RequestA
  19. muimaster.library/MUI_RejectIDCMP
  20. muimaster.library/MUI_RequestIDCMP
  21. muimaster.library/MUI_SetError
  22.  
  23.  
  24. muimaster.library/--background--             muimaster.library/--background--
  25.  
  26.     PURPOSE
  27.     muimaster.library contains functions for creating and diposing
  28.     objects, for requester handling and for controlling custom
  29.     classes. Additionally, several of the standard MUI classes are
  30.     built into muimaster.library. For you as a programmer, there
  31.     is no difference between using a builtin class or an external
  32.     class coming as "mui:libs/mui/<foobar>.mui". The MUI object
  33.     generation call takes care of this situation and loads
  34.     external classes automatically when they are needed.
  35.  
  36.  
  37. muimaster.library/MUI_AllocAslRequest   muimaster.library/MUI_AllocAslRequest
  38.  
  39.     NAME
  40.     MUI_AllocAslRequest
  41.  
  42.     FUNCTION
  43.     Provide an interface to asl.library. Using this ensures
  44.     your application will benefit from future expansions
  45.         to MUI's window and iconification handling.
  46.  
  47.     SEE ALSO
  48.     asl.library/AllocAslRequest
  49.  
  50.  
  51. muimaster.library/MUI_AslRequest
  52.  
  53.     NAME
  54.     MUI_AslRequest
  55.  
  56.     FUNCTION
  57.     Provide an interface to asl.library. Using this ensures
  58.     your application will benefit from future expansions
  59.         to MUI's window and iconification handling.
  60.  
  61.     SEE ALSO
  62.     asl.library/AslRequest
  63.  
  64.  
  65. muimaster.library/MUI_CreateCustomClass                 MUI_CreateCustomClass
  66.  
  67.     NAME
  68.     MUI_CreateCustomClass -- create a public/private custom class.
  69.  
  70.     SYNOPSIS
  71.     MUI_CreateCustomClass (base, supername, supermcc, datasize, dispfunc)
  72.                             A0    A1        A2        D0        A3
  73.  
  74.     struct MUI_CustomClass * MUI_CreateCustomClass(
  75.        struct Library *, char *, int, APTR );
  76.  
  77.     FUNCTION
  78.     This function creates a public or private MUI custom class.
  79.     Public custom classes are shared libraries and can be found
  80.     in "libs:mui/<foobar>.mcc". Private classes simply consist
  81.     of a dispatcher and are built into applications.
  82.  
  83.     MUI_CreateCustomClass() returns a pointer to a struct
  84.     MUI_CustomClass which in turn contains a pointer to a
  85.     struct IClass. For private classes, this struct IClass
  86.     pointer needs to be fed to a intuition.library/NewObject()
  87.     call to create new objects.
  88.  
  89.     MUI creates the dispatcher hook for you, you may *not*
  90.     use the IClass->cl_Dispatcher.h_Data field! If you need
  91.     custom data for your dispatcher, use the cl_UserData
  92.     of the IClass structure or the mcc_UserData of the
  93.     MUI_CustomClass structure.
  94.  
  95.     For public classes, MUI makes sure that a6 contains
  96.     a pointer to your library base when your dispatcher
  97.     is called. For private classes, you will need to keep
  98.     track of A4 or similiar things the compiler may need yourself.
  99.  
  100.     INPUTS
  101.     base =      if you create a public class, you have to call
  102.                 MUI_CreateCustomClass() from your libraries
  103.                 init function. In this case, place your library
  104.                 base pointer here. For private classes, you must
  105.                 supply NULL.
  106.  
  107.     supername = super class of your class. This can either
  108.                 be a builtin MUI class ("xyz.mui") or a external
  109.                 custom class ("xyz.mcc").
  110.  
  111.     supermcc =  if (and only if) the super class is a private
  112.                 custom class and hence has no name, you are allowed
  113.                 to pass a NULL supername and a pointer to the
  114.                 MUI_CustomClass structure of the super class here.
  115.  
  116.     datasize =  size of your classes data structure.
  117.  
  118.     dispfunc =  your classes dispatcher function (no hook!).
  119.                 The dispatcher will be called with a struct IClass
  120.                 in a0, with your object in a2 and the message in a1.
  121.  
  122.     RESULT
  123.     A pointer to a struct MUI_CustomClass or NULL to indicate
  124.     an error.
  125.  
  126.     SEE ALSO
  127.     MUI_DeleteCustomClass()
  128.  
  129.  
  130. muimaster.library/MUI_DeleteCustomClass                 MUI_DeleteCustomClass
  131.  
  132.     NAME
  133.     MUI_DeleteCustomClass -- delete a public/private custom class.
  134.  
  135.     SYNOPSIS
  136.     MUI_DeleteCustomClass ( mcc )
  137.                             A0
  138.  
  139.     BOOL MUI_DeleteCustomClass(struct MUI_CustomClass *);
  140.  
  141.     FUNCTION
  142.     Delete a public or private custom class. Note that you
  143.     must not delete classes with outstanding objects or sub
  144.     classes.
  145.  
  146.     INPUTS
  147.     mcc = pointer obtained from MUI_CreateCustomClass().
  148.  
  149.     RESULT
  150.     TRUE if all went well, FALSE if some objects or
  151.     sub classes were still hanging around. Nothing
  152.     will be freed in this case.
  153.  
  154.     SEE ALSO
  155.     MUI_CreateCustomClass()
  156.  
  157.  
  158. muimaster.library/MUI_DisposeObject       muimaster.library/MUI_DisposeObject
  159.  
  160.     NAME
  161.     MUI_DisposeObject -- Delete a MUI object.
  162.  
  163.     SYNOPSIS
  164.     MUI_DisposeObject( object )
  165.                        A0
  166.  
  167.     VOID MUI_DisposeObject( APTR );
  168.  
  169.     FUNCTION
  170.     Deletes a MUI object and all of it's auxiliary data.
  171.     These objects are all created by MUI_NewObject() or NewObject().
  172.     Objects of certain classes "own" other objects, which will also
  173.     be deleted when the object is passed to MUI_DisposeObject().
  174.     Read the per-class documentation carefully to be aware
  175.     of these instances.
  176.  
  177.     INPUTS
  178.     object = abstract pointer to a MUI object returned by
  179.              MUI_NewObject(). The pointer may be NULL, in which case
  180.              this function has no effect.
  181.  
  182.     RESULT
  183.     None.
  184.  
  185.     SEE ALSO
  186.     MUI_NewObjectA(), SetAttrs(), GetAttr().
  187.  
  188.  
  189. muimaster.library/MUI_Error                       muimaster.library/MUI_Error
  190.  
  191.     NAME
  192.     MUI_Error -- Return extra information from the MUI system.
  193.  
  194.     SYNOPSIS
  195.     LONG MUI_Error(VOID);
  196.  
  197.     FUNCTION
  198.     Obsolete. Better use SetIoErr()/IoErr().
  199.  
  200.     SEE ALSO
  201.     MUI_SetError()
  202.  
  203.  
  204. muimaster.library/MUI_FreeAslRequest     muimaster.library/MUI_FreeAslRequest
  205.  
  206.     NAME
  207.     MUI_FreeAslRequest
  208.  
  209.     FUNCTION
  210.     Provide an interface to asl.library. Using this ensures
  211.     your application will benefit from future expansions
  212.         to MUI's window and iconification handling.
  213.  
  214.     SEE ALSO
  215.     asl.library/FreeAslRequest
  216.  
  217.  
  218. muimaster.library/MUI_FreeClass               muimaster.library/MUI_FreeClass
  219.  
  220.     NAME
  221.      MUI_FreeClass -- Free class.
  222.  
  223.     SYNOPSIS
  224.     MUI_FreeClass( classptr )
  225.                    A0
  226.  
  227.     VOID MUI_FreeClass(struct IClass *classptr);
  228.  
  229.     FUNCTION
  230.     This function is obsolete since MUI V8.
  231.     Use MUI_DeleteCustomClass() instead.
  232.  
  233.     SEE ALSO
  234.     MUI_CreateCustomClass(), MUI_DeleteCustomClass()
  235.  
  236.  
  237. muimaster.library/MUI_GetClass                 muimaster.library/MUI_GetClass
  238.  
  239.     NAME
  240.      MUI_GetClass -- Get a pointer to a MUI class.
  241.  
  242.     SYNOPSIS
  243.     class = MUI_GetClass( classid )
  244.     D0                    A0
  245.  
  246.     struct IClass * MUI_GetClass(char *classid);
  247.  
  248.     FUNCTION
  249.     This function is obsolete since MUI V8.
  250.     Use MUI_CreateCustomClass instead.
  251.  
  252.     SEE ALSO
  253.     MUI_CreateCustomClass(), MUI_DeleteCustomClass()
  254.  
  255.  
  256. muimaster.library/MUI_MakeObjectA           muimaster.library/MUI_MakeObjectA
  257.  
  258.     NAME
  259.      MUI_MakeObjectA -- create an object from the builtin object collection.
  260.      MUI_MakeObject -- Varargs stub for MUI_MakeObjectA
  261.  
  262.     SYNOPSIS
  263.     object = MUI_MakeObjectA( objtype, params )
  264.     D0                        D0       A0
  265.  
  266.     Object * MUI_MakeObjectA(ULONG type, ULONG *params);
  267.  
  268.     Object * MUI_MakeObject(ULONG type, ...);
  269.  
  270.     FUNCTION
  271.     Prior to muimaster.library V8, MUI was distributed with several macros
  272.     to help creating often used objects. This practice was easy, but using
  273.     lots of these macros often resulted in big programs. Now, muimaster
  274.     library contains an object library with several often used objects
  275.     already built in.
  276.  
  277.     MUI_MakeObject() takes the type of the object as first parameter and
  278.     a list of additional (type specific) parameters. Note that these
  279.     additional values are *not* a taglist!
  280.  
  281.     See the header file mui.h for documentation on object types and the
  282.     required parameters.
  283.  
  284.     SEE ALSO
  285.     MUI_CreateCustomClass(), MUI_DeleteCustomClass()
  286.  
  287.  
  288. muimaster.library/MUI_NewObjectA             muimaster.library/MUI_NewObjectA
  289.  
  290.    NAME
  291.     MUI_NewObjectA -- Create an object from a class.
  292.     MUI_NewObject -- Varargs stub for MUI_NewObjectA().
  293.  
  294.    SYNOPSIS
  295.     object = MUI_NewObjectA( class, tags )
  296.     D0                       A0     A1
  297.  
  298.     APTR MUI_NewObjectA( char *, struct TagItem * );
  299.  
  300.     object = MUI_NewObject( classID, Tag1, ... )
  301.  
  302.     APTR MUI_NewObject( classID, ULONG, ... );
  303.  
  304.    FUNCTION
  305.     This is the general method of creating objects from MUI classes.
  306.     You specify a class by its ID string. If the class is not
  307.     already in memory or built into muimaster.library, it will be
  308.     loaded using OpenLibrary("mui/%s",0).
  309.  
  310.     You further specify initial "create-time" attributes for the
  311.     object via a TagItem list, and they are applied to the resulting
  312.     generic data object that is returned. The attributes, their meanings,
  313.     attributes applied only at create-time, and required attributes
  314.     are all defined and documented on a class-by-class basis.
  315.  
  316.    INPUTS
  317.     classID = the name/ID string of a MUI class, e.g. "Image.mui".
  318.               Class names are case sensitive!
  319.  
  320.     tagList = pointer to array of TagItems containing attribute/value
  321.               pairs to be applied to the object being created.
  322.  
  323.    RESULT
  324.     A MUI object, which may be used in different contexts such
  325.     as an application, window or gadget, and may be manipulated
  326.     by generic functions. You eventually free the object using
  327.     MUI_DisposeObject().
  328.     NULL indicates failure, more information on the error can be
  329.     obtained with MUI_Error().
  330.  
  331.    BUGS
  332.  
  333.    SEE ALSO
  334.     MUI_DisposeObject(), MUI_Error(), SetAttrs(), GetAttr().
  335.  
  336.  
  337. muimaster.library/MUI_ObtainPen               muimaster.library/MUI_ObtainPen
  338.  
  339.    NAME
  340.     MUI_ObtainPen -- Obtain a drawing pen.
  341.  
  342.    SYNOPSIS
  343.     MUI_ObtainPen ( mri , spec , flags )
  344.                     A0    A1     D0
  345.  
  346.     LONG MUI_ObtainPen
  347.     (
  348.         struct MUI_RenderInfo *mri,
  349.         struct MUI_PenSpec *spec,
  350.         ULONG flags
  351.     );
  352.  
  353.    FUNCTION
  354.     Whenever your application needs custom drawing pens, you should allow
  355.     your user to adjust them with a Poppen class. The result from this
  356.     Poppen class is a struct MUI_PenSpec which you can save somewhere in
  357.     your preferences and use together with MUI_ObtainPen(),
  358.     MUI_ReleasePen() and the MUIPEN() macro to transform the spec into a
  359.     pen number useful for SetAPen().
  360.  
  361.    NOTE
  362.     This function will work under 2.x but will generally perform better
  363.     under 3.x and above.
  364.  
  365.    EXAMPLE
  366.     See demo program Class2.c
  367.  
  368.    SEE ALSO
  369.     MUI_ReleasePen(), Poppen.mui
  370.  
  371.  
  372.  
  373. muimaster.library/MUI_Redraw                     muimaster.library/MUI_Redraw
  374.  
  375.    NAME
  376.     MUI_Redraw -- Redraw yourself.
  377.  
  378.    SYNOPSIS
  379.     MUI_Redraw( obj, flag )
  380.                 A0   D0
  381.  
  382.     VOID MUI_Redraw( Object *obj, ULONG flag );
  383.  
  384.    FUNCTION
  385.     With MUI_Redraw(), an object tells itself to refresh, e.g. when
  386.     some internal attributes were changed. Calling MUI_Redraw() is
  387.     only legal within a custom class dispatcher, using this function
  388.     within an applications main part is invalid!
  389.  
  390.     Most objects graphical representation in a window depends on some
  391.     attributes. A fuel gauge for example would depend on its
  392.     MUIA_Gauge_Current attribute, an animation object would
  393.     depend on MUIA_Animation_CurrentFrame.
  394.  
  395.     Whenever someone changes such an attribute with a SetAttrs() call,
  396.     the corresponding object receives an OM_SET method with the new
  397.     value. Usually, it could just render itself with some
  398.     graphics.library calls. However, if the object is placed
  399.     in a virtual group or if some other clipping or coordinate
  400.     translation is required, this simple rendering will lead
  401.     into problems.
  402.  
  403.     That's why MUI offers the MUI_Redraw() function call. Instead
  404.     of drawing directly during OM_SET, you should simply call
  405.     MUI_Redraw(). MUI calculates all necessary coordinates
  406.     and clip regions (in case of virtual groups) and then sends
  407.     a MUIM_Draw method to your object.
  408.  
  409.     To emphasize this point again: The only time your object is
  410.     allowed to render something is when you receive a MUIM_Draw
  411.     method. Drawing during other methods is illegal.
  412.  
  413.     Note: As long as no special cases (e.g. virtual groups) are
  414.           present, MUI_Redraw is very quick and calls your MUIM_Draw
  415.           method immediately. No coordinate translations or clip
  416.           regions need to be calculated.
  417.  
  418.    INPUTS
  419.     obj  - pointer to yourself.
  420.     flag - MADF_DRAWOBJECT or MADF_DRAWUPDATE.
  421.            The flag given here affects the objects flags when
  422.            MUI calls the MUIM_Draw method. There are several
  423.            caveats when implementing MUIM_DRAW, see the
  424.            developer documentation for details.
  425.  
  426.    EXAMPLE
  427.  
  428.     /* Note: This example was broken up to version 2.1 of muimaster.doc */
  429.  
  430.     LONG mSet(struct IClass *cl,Object *obj,sruct opSet *msg)
  431.     {
  432.        struct Data *data = INST_DATA(cl,obj);
  433.        struct TagItem *tags,*tag;
  434.  
  435.        for (tags=msg->ops_AttrList;tag=NextTagItem(&tags);)
  436.        {
  437.           switch (tag->ti_Tag)
  438.           {
  439.              case MYATTR_PEN_1:
  440.                 data->pen1 = tag->ti_Data;       /* set the new value  */
  441.                 data->mark = 1;                  /* set internal marker*/
  442.                 MUI_Redraw(obj,MADF_DRAWUPDATE); /* update ourselves   */
  443.                 break;
  444.  
  445.              case MYATTR_PEN_1:
  446.                 data->pen2 = tag->ti_Data;       /* set the new value  */
  447.                 data->mark = 2;                  /* set internal marker*/
  448.                 MUI_Redraw(obj,MADF_DRAWUPDATE); /* update ourselves   */
  449.                 break;
  450.           }
  451.        }
  452.  
  453.        return(DoSuperMethodA(cl,obj,msg));
  454.     }
  455.  
  456.     LONG mDraw(struct IClass *cl,Object *obj,struct MUIP_Draw *msg)
  457.     {
  458.        struct Data *data = INST_DATA(cl,obj);
  459.  
  460.        // ** Note: You *must* call the super method prior to do
  461.        // ** anything else, otherwise msg->flags will not be set
  462.        // ** properly !!!
  463.  
  464.        DoSuperMethodA(cl,obj,msg); // ALWAYS REQUIRED!
  465.  
  466.        if (msg->flags & MADF_DRAWUPDATE)
  467.        {
  468.           /* called as a result of our MUI_Redraw() during
  469.              MUIM_Set method. Depending on our internal
  470.              marker, we render different things. */
  471.  
  472.           switch (data->mark)
  473.           {
  474.              case 1: RenderChangesFromPen1(cl,obj); break;
  475.              case 2: RenderChangesFromPen2(cl,obj); break;
  476.           }
  477.        }
  478.        else if (msg->flags & MADF_DRAWOBJECT)
  479.        {
  480.           /* complete redraw, maybe the window was just opened. */
  481.           DrawObjectCompletely(cl,obj);
  482.        }
  483.  
  484.        /* if MADF_DRAWOBJECT wasn't set, MUI just wanted to update
  485.           the frame or some other part of our object. In this case
  486.           we just do nothing. */
  487.  
  488.         return(0);
  489.     }
  490.  
  491.    SEE ALSO
  492.     area.mui/MUIM_Draw
  493.  
  494.  
  495. muimaster.library/MUI_ReleasePen             muimaster.library/MUI_ReleasePen
  496.  
  497.    NAME
  498.     MUI_ObtainPen -- Obtain a drawing pen.
  499.  
  500.    SYNOPSIS
  501.     MUI_ReleasePen ( mri , pen )
  502.                      A0    D0
  503.  
  504.     LONG MUI_ReleasePen
  505.     (
  506.         struct MUI_RenderInfo *mri,
  507.         ULONG pen
  508.     );
  509.  
  510.    FUNCTION
  511.     Release a pen obtained with MUI_ObtainPen(). Usually placed
  512.     in the Cleanup method of custom classes.
  513.  
  514.    NOTE
  515.     Do *not* use the MUIPEN() maros when releasing pens!
  516.  
  517.    EXAMPLE
  518.     See demo program Class2.c
  519.  
  520.    SEE ALSO
  521.     MUI_ObtainPen(), Poppen.mui
  522.  
  523.  
  524.  
  525. muimaster.library/MUI_RequestA                 muimaster.library/MUI_RequestA
  526.  
  527.    NAME
  528.     MUI_RequestA  -- Pop up a MUI requester.
  529.  
  530.    SYNOPSIS
  531.     MUI_RequestA(app,win,flags,title,gadgets,format,params)
  532.                  D0   D1  D2    A0     A1      A2     A3
  533.  
  534.     LONG MUI_RequestA ( APTR app, APTR win, LONGBITS flags,
  535.          char *title, char *gadgets, char *format, APTR params );
  536.  
  537.     LONG MUI_Request ( APTR app, APTR win, LONGBITS flags,
  538.          char *title, char *gadgets, char *format, ...);
  539.  
  540.    FUNCTION
  541.     Pop up a MUI requester. Using a MUI requester instead
  542.     of a standard system requester offers you the possibility
  543.     to include text containing all the text engine format codes.
  544.  
  545.    INPUTS
  546.     app     - The application object. If you leave this
  547.               NULL, MUI_RequestA() will fall back to a
  548.               standard system requester.
  549.  
  550.     win     - Pointer to a window of the application. If
  551.               this is used, the requester will appear centered
  552.               relative to this window.
  553.  
  554.     flags   - For future expansion, must be 0 for now.
  555.  
  556.     title   - Title for the requester window. Defaults to the
  557.               name of the application when NULL (and app!=NULL).
  558.  
  559.     gadgets - Pointer to a string containing the possible answers.
  560.               The format looks like "_Save|_Use|_Test|_Cancel".
  561.               If you precede an entry with a '*', this answer will
  562.               become the active object. Pressing <Return> will
  563.               terminate the requester with this response. A '_'
  564.               character indicates the keyboard shortcut for this
  565.               response.
  566.  
  567.     format  - A printf-style formatting string.
  568.  
  569.     params  - Pointer to an array of ULONG containing the parameter
  570.               values for format.
  571.  
  572.    RESULT
  573.     0, 1, ..., N = Successive id values, for the gadgets
  574.     you specify for the requester.  NOTE: The numbering
  575.     from left to right is actually: 1, 2, ..., N, 0.
  576.     In case of a problem (e.g. out of memory), the
  577.     function returns FALSE.
  578.  
  579.    SEE ALSO
  580.     MUIA_Text_Contents
  581.  
  582.  
  583. muimaster.library/MUI_RejectIDCMP           muimaster.library/MUI_RejectIDCMP
  584.  
  585.    NAME
  586.      MUI_RejectIDCMP -- Reject previously requested input events.
  587.  
  588.    SYNOPSIS
  589.     MUI_RejectIDCMP( obj, flags )
  590.                       A0   D0
  591.  
  592.     VOID MUI_RejectIDCMP( Object *obj, ULONG flags );
  593.  
  594.    FUNCTION
  595.     Reject previously requested input events. You should
  596.     ensure that you reject all input events you requested
  597.     for an object before it gets disposed. Rejecting
  598.     flags that you never requested has no effect.
  599.  
  600.     Critical flags such as IDCMP_MOUSEMOVE and IDCMP_INTUITICKS
  601.     should be rejected as soon as possible. See MUI_RequestIDCMP()
  602.     for details.
  603.  
  604.    INPUTS
  605.     obj   - pointer to yourself as an object.
  606.     flags - one or more IDCMP_XXXX flags.
  607.  
  608.    EXAMPLE
  609.     LONG CleanupMethod(struct IClass *cl, Object *obj, Msg msg)
  610.     {
  611.        MUI_RejectIDCMP( obj, IDCMP_MOUSEBUTTONS|IDCMP_RAWKEY );
  612.        return(DoSuperMethodA(cl,obj,msg));
  613.     }
  614.  
  615.    SEE ALSO
  616.     MUI_RequestIDMCP()
  617.  
  618.  
  619. muimaster.library/MUI_RequestIDCMP         muimaster.library/MUI_RequestIDCMP
  620.  
  621.    NAME
  622.      MUI_RequestIDCMP -- Request input events for your custom class.
  623.  
  624.    SYNOPSIS
  625.     MUI_RequestIDCMP( obj, flags )
  626.                       A0   D0
  627.  
  628.     VOID MUI_RequestIDCMP( Object *obj, ULONG flags );
  629.  
  630.    FUNCTION
  631.     If your custom class needs to do some input handling, you must
  632.     explicitly request the events you want to receive. You can
  633.     request (and reject) events at any time.
  634.  
  635.     Whenever an input event you requested arrives at your parent
  636.     windows message port, your object will receive a
  637.     MUIM_HandleInput method.
  638.  
  639.     Note: Time consuming IDCMP flags such as IDCMP_INTUITICKS and
  640.           IDCMP_MOUSEMOVE should be handled with care. Too many
  641.           objects receiving them will degrade performance With
  642.           the following paragraph in mind, this isn't really
  643.           a problem:
  644.  
  645.           You should try to request critical events only when you
  646.           really need them and reject them with MUI_RejectIDCMP()
  647.           as soon as possible. Usually, mouse controlled objects
  648.           only need MOUSEMOVES and INTUITICKS when a button
  649.           is pressed. You should request these flags only
  650.           on demand, i.e. after receiving a mouse down event
  651.           and reject them immediately after the button has been
  652.           released.
  653.  
  654.    INPUTS
  655.     obj   - pointer to yourself as an object.
  656.     flags - one or more IDCMP_XXXX flags.
  657.  
  658.    EXAMPLE
  659.     LONG SetupMethod(struct IClass *cl, Object *obj, Msg msg)
  660.     {
  661.        if (!DoSuperMethodA(cl,obj,msg))
  662.           return(FALSE);
  663.  
  664.        /* do some setup here... */
  665.        ...;
  666.  
  667.        /* i need mousebutton events and keyboard */
  668.        MUI_RequestIDCMP( obj, IDCMP_MOUSEBUTTONS|IDCMP_RAWKEY );
  669.  
  670.        return(TRUE);
  671.     }
  672.  
  673.    SEE ALSO
  674.     MUI_RejectIDMCP()
  675.  
  676.  
  677. muimaster.library/MUI_SetError                 muimaster.library/MUI_SetError
  678.  
  679.    NAME
  680.      MUI_SetError -- Set an error value.
  681.  
  682.    SYNOPSIS
  683.     VOID MUI_SetError(LONG);
  684.  
  685.    FUNCTION
  686.     Obsolete. Better use SetIoErr()/IoErr().
  687.  
  688.    SEE ALSO
  689.     MUI_Error()
  690.